Description

Improves row-decoder throughput by synchronously consuming fixed-width scalars that are already buffered in NetworkTransport. A buffer miss falls back to the existing async TDS packet read/refill path and retries, so packet framing and error handling remain authoritative.

The optimized decoder reads cover byte, little-endian i16, u16, 24-bit u32, i32, u32, 40-bit u64, i64, f32, and f64. This is a standalone runtime optimization informed by measurements from #269. It does not revive that PR or retry decoder convergence.

Stack position

This draft is stacked directly on #291 (Remove ResultSet async_trait boxing) in native stack #287. Its incremental diff is the two buffered-read commits above #291; the current open chain is #286 → #291 → this PR.

Implementation

• Adds explicit non-consuming-on-miss probes to both TdsPacketReader configurations, with safe None defaults for other readers.
• Implements direct fixed-width probes in TdsReadBuffer and delegates them from NetworkTransport.
• Uses one parameterized read_sync_first! macro at every production fixed-width scalar read in datatypes/decoder.rs.
• Keeps read_tds_packet() as the only refill path for async misses.
• Leaves big-endian packet/header reads and u64 reads outside the decoder unchanged.

Before and after

Before: every scalar enters the async path

sequenceDiagram
    participant D as Decoder
    participant A as async read_*()
    participant B as TdsReadBuffer
    participant P as Packet I/O

    D->>A: read_*().await
    Note over D,A: Construct and poll a future for every scalar
    A->>B: Enough bytes buffered?
    alt Buffered hit
        B-->>A: Yes
        A->>B: Consume N bytes
        A-->>D: Ready(value)
    else Buffer miss
        B-->>A: No
        A->>P: read_tds_packet().await
        P-->>A: Next framed payload
        A->>B: Retry and consume N bytes
        A-->>D: Ready(value)
    end

After: synchronous probe before async fallback

sequenceDiagram
    participant D as Decoder
    participant M as sync-first macro
    participant T as NetworkTransport
    participant B as TdsReadBuffer
    participant P as Packet I/O

    D->>M: read_sync_first!
    M->>T: try_read_*() [sync]
    T->>B: Probe complete N-byte scalar
    alt Buffered hit
        B-->>T: Some(value), consume N bytes
        T-->>M: Some(value)
        M-->>D: value
        Note over D,M: No async future constructed or polled
    else Buffer miss
        B-->>T: None, consume zero bytes
        T-->>M: None
        M->>T: read_*().await
        T->>P: read_tds_packet().await
        P-->>T: Next framed payload
        T->>B: Refill, retry, consume complete scalar
        T-->>M: Ok(value)
        M-->>D: value
    end

N is the scalar's fixed wire width (1, 2, 3, 4, 5, or 8 bytes). Packet framing, cancellation, encryption, and errors remain in the existing async fallback.

Correctness coverage

Targeted tests cover successful buffered reads, zero consumption when any supported scalar is incomplete, and every supported scalar split across real TDS packet boundaries through NetworkTransport. Existing NULL and length-marker handling remains unchanged.

Production-reader benchmarks

All benchmarks use concrete NetworkTransport, packetized in-memory input, 7,992-byte packet payloads, 30,000 rows per pass, 2 warmups, 9 measured passes per cell, and 8 paired rounds alternating baseline/candidate order. Negative deltas are faster.

Stacked result versus #291 (8c6ff8b2)

The stack comparison used identical lockfiles and isolated source/target directories. The #291 and stacked test binaries had different SHA-256 hashes.

Initial change versus clean main (ac1023a1)

Expanded fixed-width reads versus the first draft (47c2fb68)

The fixed_scalars workload has 64 columns: Int1, Int2, Int4, Int8, Flt4, Flt8, DateTime, and DateTim4, repeated eight times.

The optimized pre-stack benchmark executable grew by about 192 KB (1.75%), so code-size impact remains a review consideration.

Validation

• cargo bfmt
• cargo bclippy
• $env:RUSTFLAGS='--cfg fuzzing'; cargo check -p mssql-tds --lib
• Rebased full mssql-tds library nextest suite with generated TLS fixtures: 1,764 passed
• Stacked production-reader benchmark against Remove ResultSet async_trait boxing #291: all six paired medians improved
• GitHub CodeQL, linked-issue, CLA, and coverage checks pass
• Stacked main...HEAD coverage: 98% diff coverage and 91.5% overall coverage
• The external ADO build policy skips dependent-branch PRs; the same buffered-read commits passed its full cross-platform matrix before restacking (build 167366)
• cargo btest was attempted locally before stacking but the live SQL integration tests fail with Schannel SEC_E_WRONG_PRINCIPAL.

Risk

The fast path is limited to already-buffered decoder scalars on NetworkTransport. Other packet readers retain their existing async behavior through default None probes. Misses preserve partial bytes and reuse the existing refill path, including cancellation and encryption behavior. The broader set of inlined probes trades some code size for lower per-value async overhead.

Related Issues

Related to #247.

Stacked on #291.

Historical measurement context: #269.

Checklist

• cargo bfmt passes
• cargo bclippy passes
• cargo btest passes locally (environment-blocked; pre-stack remote matrix passes)
• New/changed functionality has tests
• Public API changes are documented